# Configure a provider for a scope

Sets or updates the API key and auth configuration for a provider in the given scope. Creates a scoped provider record if one doesn't exist.

RBAC:
- requires ANY of AIProviders.Manage, GroupAIProviders.Manage

Endpoint: PUT /api/v1/ai-providers/{providerId}/configure
Version: 1.0
Security: header

## Path parameters:

  - `providerId` (string, required)
    UUID with type prefix
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

## Query parameters:

  - `scope` (string, required)
    Scope: 'global' or group TypeId

## Request fields (application/json):

  - `authType` (string)
    Authentication type
    Enum: "API_KEY", "OAUTH2", "NONE"

  - `authSecret` (string,null)
    API key or secret (will be encrypted)

  - `clearAuthSecret` (boolean)
    Clear stored auth secret

## Response 200 fields (application/json):

  - `providerId` (string, required)
    Provider unique identifier (catalog)
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `providerType` (string, required)
    Type of the AI provider
    Enum: "OPENAI", "OPENROUTER", "GOOGLE", "ANTHROPIC"

  - `name` (string, required)
    Display name for the provider

  - `configured` (boolean, required)
    Whether provider is configured (has a scoped record) in this scope

  - `hasApiKey` (boolean, required)
    Whether this provider has an API key configured in this scope

  - `apiKeyPreview` (string,null, required)
    Masked preview of the stored API key (provider prefix + first few unique chars)
    Example: "sk-abcd..."

  - `apiKeyFormatHint` (object, required)
    Lightweight API key format hint for this provider type

  - `apiKeyFormatHint.prefixes` (array, required)
    Accepted key prefixes
    Example: ["sk-"]

  - `apiKeyFormatHint.exampleMasked` (string, required)
    Masked key example
    Example: "sk-...abcd"

  - `apiKeyFormatHint.rule` (string, required)
    Human-readable format guidance

  - `apiKeyFormatHint.docsUrl` (string, required)
    Documentation URL for obtaining and managing keys

  - `apiKeyFormatHint.regexHint` (string, required)
    Loose validation regex hint

  - `logoUrl` (string,null, required)
    URL to provider logo
    Example: "https://models.dev/logos/openai.svg"

  - `createdAt` (string, required)
    When the provider was created
    Example: "2022-03-10T16:15:50Z"

  - `updatedAt` (string, required)
    When the provider was last updated
    Example: "2022-03-10T16:15:50Z"

## Response 400 fields (application/json):

  - `errorCode` (string, required)
    Error code

  - `message` (string, required)
    Error message

  - `docUrl` (string)
    Link to documentation

## Response 401 fields (application/json):

  - `errorCode` (string, required)
    Error code

  - `message` (string, required)
    Error message

  - `docUrl` (string)
    Link to documentation

## Response 403 fields (application/json):

  - `errorCode` (string, required)
    Error code

  - `message` (string, required)
    Error message

  - `docUrl` (string)
    Link to documentation

## Response 404 fields (application/json):

  - `errorCode` (string, required)
    Error code

  - `message` (string, required)
    Error message

  - `docUrl` (string)
    Link to documentation